/**
 * @(#)DatabaseInterface.java        1.0 2/26/12
 * 
 * Copyright (c) 2012 public static droid main
 * Georgia Institute of Technology, Atlanta, GA
 * All rights reserved.
 */
package edu.gatech.oad.publicstaticdroidmain.taskmanager.persistence;

import java.util.Date;

import edu.gatech.oad.publicstaticdroidmain.taskmanager.model.Task;

/**
 * An interface for databases that store and manipulate TaskManager 
 * data.
 * 
 * @author RaheelMerali
 */
public interface DataSourceInterface {
    /**
     * Readies this database for use.  You must call this method before
     * attempting to use any of the other methods in this class.
     */
    void open();
    
    /**
     * Closes the connection to the underlying Android database.  Call this
     * method when you are finished using this database object.  After calling
     * this method, none of the other methods in this class will work.  If
     * you want to reuse this database object after calling this method, you
     * need to call open() on it again.
     */
    void close();
    
    /**
     * Determines whether a user with the specified username exists in this
     * database.
     * 
     * @param username the username whose existence is to be determined
     * @return true if the specified username exists in this database; false
     * 		otherwise
     */
    boolean userExists(String username);
    
    /**
     * Determines whether the specified username-password combination corresponds
     * to an actual account in the database.
     * 
     * @param username the username of the account
     * @param password the password of the account
     * @return true if the specified username-password combination is valid;
     * 		false otherwise
     */
    boolean verifyCredentials(String username, String password);
    
    /**
     * Creates a user in the database with the specified information if
     * an account with the specified username does not already exist.
     * 
     * @param username the username of the account to create
     * @param password the password of the account to create
     * @param realName the real name of the person who owns this account
     * @param emailAddress the email address of the person who owns this account
     * @return true if the account was successfully created; false if an account
     * 		with the specified username already exists
     */
    boolean createUser(String username, String password, String realName, String emailAddress);
    
    /**
     * Changes the specified username to the specified new username.
     * 
     * @param username the username to change
     * @param newUsername the new username
     * @return true if the username was successfully updated; false if
     * 		the specifide username does not exist
     */
    boolean updateUsername(String username, String newUsername);
    
    /** 
     * Changes the password of the account with the specified username to
     * the new specified password.
     * 
     * @param username the username of the account to edit
     * @param oldPassword the account's current password
     * @param newPassword the new password
     * @return true if the password was successfully changed; false if the
     * 		specified username does not exist or if the old password
     * 		is incorrect
     */
    boolean updatePassword(String username, String oldPassword, String newPassword);
    
    /** 
     * Changes the real name of the account with the specified username to
     * the new specified real name.
     * 
     * @param username the username of the account to edit
     * @param newRealName the new real name
     * @return true if the real name was successfully changed; false if the
     * 		specified username does not exist
     */
    boolean updateRealName(String username, String newRealName);
    
    /** 
     * Changes the email address of the account with the specified username to
     * the specified new email address.
     * 
     * @param username the username of the account to edit
     * @param newEmailAddress the new email address
     * @return true if the email address was successfully changed; false if the
     * 		specified username does not exist
     */
    boolean updateEmailAddress(String username, String newEmailAddress);
    
    /**
     * Returns the real name of the account with the specified username.
     * 
     * @param username the username of the account
     * @return the real name of the account with the specified username
     */
    String getRealName(String username);
    
    /**
     * Returns the email address of the account with the specified username.
     * 
     * @param username the username of the account
     * @return the email address of the account with the specified username
     */
    String getEmailAddress(String username);
    
    /**
     * Adds the specified category to the account with the specified
     * username.
     * 
     * @param username the username of the account
     * @param category the name of the category to add
     * @return true if the category was successfully added; false if
     * 		the category already exists
     */
    boolean addCategory(String username, String category);
    
    /**
     * Changes the name of of the specified category to the specified new name.
     * 
     * @param username the username of the account to edit
     * @param oldName the name of the category whose name to change
     * @param newName the new name for the category
     * @return true if the category's name was successfully changed; false if
     * 		the specified category does not exist
     */
    boolean updateCategoryName(String username, String oldName, String newName);
    
    /**
     * Removes the category with the specified name from the specified
     * user's account and places the tasks in that category into the
     * specified replacement category.
     * 
     * @param username the username of the account
     * @param category the name of the category to remove
     * @param replacement the name of the category in which to place the 
     * 		tasks in the deleted category
     * @return true if the specified category was successfully removed;
     * 		false if the specified category does not exist
     */
    boolean removeCategory(String username, String category, String replacement);
    
    /**
     * Determines whether the specified category exists in the specified
     * username's account.
     * 
     * @param username the username of the account
     * @param password the name of the category whose existence to determine
     * @return true if the specified category exists; false otherwise
     */
    boolean categoryExists(String username, String category);
    
    /**
     * Generates an array containing the names of the categories in the
     * specified account.
     * 
     * @param username the username of the account
     * @return an array containing the names of the categories in the
     * 		specified account
     */
    String[] getCategories(String username);
    
    /**
     * Generates an array containing the Tasks in the specified category
     * in the specified account.
     * 
     * @param username the username of the account
     * @param category the name of the category whose Tasks to retrieve
     * @return an array containing the Tasks in the specified category
     */
    Task[] getTasksInCategory(String username, String category);
    
    /**
     * Generates an array containing the Tasks on or after the specified
     * date in the specified account.
     * 
     * @param username the username of the account
     * @param date the dividing date
     * @return an array containing the Tasks on or after the specified date
     */
    Task[] getTasksAfterDate(String username, Date date);
    
    /**
     * Generates an array containing the Tasks in with the specified completion
     * status in the specified account.
     * 
     * @param username the username of the account
     * @param completionStatus the completion status of the Tasks to retrieve
     * @return an array containing the Tasks with the specified completion status
     */
    Task[] getTasksWithCompletionStatus(String username, boolean completionStatus);
    
    /**
     * Adds the specified Task to the account with the specified username.
     * 
     * @param username the username of the account
     * @param t the Task to add to the account
     * @return true if the Task was successfully added; false if a Task with
     * 		the ID of the specified Task already exists in the account
     */
    boolean addTask(String username, Task task);
    
    /**
     * Updates the specified Task's information in the database.
     * 
     * @param username the username of the account
     * @param t the Task to update
     * @param true if the Task was successfully updated; false if the
     * 		Task does not exist in the database
     */
    boolean updateTask(String username, Task task);
    
    /**
     * Removes the Task with the specified ID from the account.
     * 
     * @param username the username of the account
     * @param id the ID of the Task to remove
     * @return true if the Task was successfully removed; false if a Task
     * 		with the specified ID does not exist
     */
    boolean removeTask(String username, long id);
    
    /**
     * Generates a Task object containing the information of the Task
     * with the specified ID.
     * 
     * @param the username of the account
     * @param id the ID of the Task whose information to retrieve
     * @param a Task object containing the specified Task's information;
     * 		null if a Task with the specified ID does not exist
     */
    Task getTask(String username, long id);
    
    /**
     * Returns an array containing all of the Tasks in the specified account.
     * 
     * @param username the username of the account
     * @return an array containing all of the Tasks in the specified account
     */
    Task[] getAllTasks(String username);
    
    void clear();
}
